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the Most Out of Your 


. Microtec Research 
| ANSI C Compiler 


Introduction 


The release of the Microtec Research ANSI C Compiler 
represents an evolutionary step forward in the development 
of optimizing compiler technology. The compiler features 
| much more than just ANSI Standard compliance; it includes 


development of embedded systems software. 


numerous other features and extensions that aid in the 


ol To help you reap the maximum benefit from the compiler, this 
manual focuses on five major areas of compiler usage: 


ANSI and Microtec Research extensions to the C language 
Enhanced compiler diagnostics 

The compilation driver and its applications 

The use of compiler features when providing test cases 


Miscellaneous applications tips 


Note: PC users should note that although the orientation of this document is towards UNIX, the information here does 
apply to MS-DOS-hosted cross compilers. The compile options and the general functioning are the same on 


C* both development platforms. 
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About This Manual 


This manual describes how to get the most out of a Microtec 
Research ANSI C Compiler. The techniques described here 
can be applied to the following compilers: 


MCC68K Version 4.0 or above 
MCC88K all versions 
MCC960 all versions 


Consequently, in examples, you will find command lines such 
as this: 


mccxxX 


where the xx represents the mnemonic for your compiler. The 
following table lists the mnemonics for each compiler 
supported by this manual. 


Compiler Mnemonic 


MCC68K 
MCC960 
MCC88K 


Specific details and examples for individual compilers can be 
found in appendices to this manual. 


Appendix A: MCC68K Considerations and Examples 
Appendix B: MCC88K Considerations and Examples 
Appendix C: MCC960 Considerations and Examples 
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(~’ ANSI and Microtec Research Extensions 


The Microtec Research ANSI C Cross Compiler provides a variety of 
| extensions to the original Kernighan and Ritchie definition of the C 
language. Some of these extensions originated with the ANSI Standard C 
| Committee; others have arisen from the desire of Microtec Research to 
| support the embedded systems programuning requirements of its 
| customers. Most of these extensions are enabled through the use of 
| compile-time options, the two most important of which are -A and -x. 


Compile-time Options 


Both -A and -x are set by default, since this is the most powerful 4 
combination. Occasionally, one may want to speafy -nA and/or -nx. 


The -A ANSI Option 


The option -A makes the compiler accept the ANSI Standard C language, as 

defined by the ANSI Committee in the X3J11 Standard. You should realize 

that using an ANSI Standard C compiler can have various, subtle 

side-effects on pre-ANSI C programs. Option -A is the default setting for the 
‘a compiler. To disable ANSI extensions, use option -nA. 


The -x Microtec Research Extension Option 


just as -A selectively activates ANSI features, the -x option activates 
Microtec Research extensions to the C language. To disable Microtec 
‘ Research extensions, use option -nx. 


ANSI Extensions 


The following sections describe the uses and implications of several ANSI 
Standard C extensions that have been implemented by Microtec Research. 
General features of ANSI are discussed, such as function prototyping, the 
implications of using floating-point in ANSI compilers, and the 
consequences of disabling ANSI features. 


Function Prototyping 


Function prototypes permit the inclusion of parameter type information 
within C function declarations. Having access to such information, the C 
compiler can detect mismatched parameter passing in terms of parameter 
type, size, and number. This optional enforcement of parameter type 
checking detects some of the most common C programming errors at 
compile-time and so promotes the engineering of more bug-free code. 
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i 
Standard library headers include ANSI and pre-ANSI declarations which ( ) 
are selectively included by the setting of -A. This mechanism can be copied 

if you do not want to give up ANSI features or lose portability with 

pre-ANSI compilers. 


#ifdef _ _STDC 


extern int remove(const char *filename) ; 


#telse 
extern int remove(); 
#endif 


Note that__STDC__ (STandarD C) is a macro defined by all 
ANSI-compliant compilers to indicate whether the ANSI Standard C 
language definition is being enforced. Use of the option -nA causes this 
macro to be undefined. 


Function prototypes are actually accepted regardless of the use of the 
compile-time option -A. When the compiler is invoked with option -nA, 
however, prototype information is flagged with an (I) Informational 


diagnostic message. ( ) 


ANSI and Floating-Point 


Example 


One interesting difference between the use of the compile-time options -A 
and -nA lies in the handling of float types. If the compiler is invoked with 
option -A, float is not converted to double unless necessary. 


#ifdef _ STDC 
assert (sizeof (float)==4); 


#felse 
assert (sizeof (float)==sizeof (double) ); 
#endif 


The example shows how the ANSI Standard C definition allows for float 
type to default to 32 bits and shows that program execution will terminate 
if this assertion is untrue, i.e., float values are not implemented as 32 bits. 


You should carefully consider the above and similar cases when migrating 
to an ANSI compiler especially if no FPU is available and software floating ( ) 
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point libraries are employed (programs compiled with -nf option). By using 
float instead of double (using the faster 32 bits instead of 64 bits), the gain 
in efficiency can be high because the compiler assists you in modifying 
programs for maximum efficiency. 


Invoking the compiler as: 


Example 


mccxx -nQ -1 flt.c 


on the file flt.c yields the following compiler listing: 


Example 


>> (I) [ANSI] inefficient evaluation in ‘double* because of "double* 
constant 


6 } 
1 Informational 


The (1) Informational message in the listing indicates that simpler 
floating-point arithmetic was prevented by the presence of a double 
operand, namely, the constant 2.0. This may result in the generation of less 
than optimal code since the variable b will be promoted to double for 
purposes of evaluation. You may want to modify the source to impose the 
type float onto the constant by either affixing the ANSI qualifier ¢ or by 
using a casting operator, as follows: 


Example 


a=b+2.0f; /* the ANSI suffix to denote a float constant */ 


az=b+(float)2.0; /* a more traditional way */ 


Disabling ANSI Features 


With the disabling option -nA, the compiler attempts to behave as much as 
possible like “a K&R implementation with common extensions’. This 
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behavior may lead you to assume that the compiler will behave exactly like e- ) 
K&R, which is not the case. Moreover, the preprocessor used with the 

compiler is definitively ANSI in nature. Consequently, evaluation 

mechanisms in the ANSI preprocessor are quite different from previous 

ones in the K&R preprocessor and other pre-ANSI preprocessors. 


The option -nA tums off ANSI features and allows the compilation of 
pre-ANSI code. The compiler, however, may not accept non-Microtec 
pre-ANSI extensions, especially if they are uncommon. 


Microtec Research Extensions 


Criteria for Using the Extensions 


10 


Just as -A selectively activates ANSI features, the -x option activates 
extensions to the C language that Microtec Research has implemented to 
ease embedded and systems programming. | 


For a list of Microtec Research extensions to ANSI C features, see Microtec 
Research Extensions in the appendix pertaining to your compiler. 


By default, the compiler enables both ANSI and Microtec Research 
extensions (options -A and -x). There are circumstances in which you may 
want to disable one or the other of these options. 


For instance, you might want to specify -nA to allow a variable named const C ) 
in your program, while with -A, const would be recognized as a keyword. 

Conversely, you may specify -nx when you want to check the value of the 

library variable errno after a sin() operation. 


Of course, specify -A and -nx when running an ANSI-compliance test. 


Getting the Most Out of Your Microtec Research ANSI C Compiler 


(> Compiler Diagnostics 


The Microtec Research compiler generates comprehensive and accurate 
diagnostic messages. Moreover, the compiler gives you more control over 
error tolerance for a given compiler invocation. 


Syntax of Diagnostic Messages 


The compiler diagnostic messages supply error descriptions (see the 
description following (E) in the following example), position markers (as 
indicated by the caret in the following example), and the level of severity of 
the message. 


The Error Position Marker 


For a line of C code containing an error, the compiler puts a “ character 
either directly under the offending element or as close to the problem as 
possible. Placement of this marker is generally accurate. 


Example 


18 psw = {{1,1,1,1,1,NoRing},1,{Supervisor, 0x1F}}; 


a 


>> (E) too many initializers for "psw' 


ANS|l-specific Diagnostics 
The [ANSI] marker appears in messages related to features which have 
been introduced or modified by the ANSI Committee. 


In the next example, the first (I) message relates to the ANSI 
recommendation to always specify a type in any declaration. The second (1) 
message points out that simple float arithmetic (as introduced by ANSI) 
was curtailed by the presence of a double operand, the constant. 


I] 
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Example 


1 array[100J; 


Aa 


>> (I} [ANSI] missing type; *int" assumed 


foo{} 


{ 
float a,b; 


a=b+2.0; 


a 


>> (I) [ANSI] inefficient evaluation in ‘double" because of ‘double* 
constant 


8 } 
2 Informacionals 


Diagnostic Severity Hierarchy 


Messages are classified according to four levels of severity: 


(F) Fatal Error 
(E) Error 

(Ww) Warning 

+9) Informational 


The implications of this hierarchy are discussed in the following 
subsections. 


Fatal Errors 
A (F) Fatal Error message immediately aborts the compilation: 


Example 


(F) can’t open file "file.c* 


Fatal errors arise from conditions which make further compilation 
impossible, such as missing source and include files, or premature 
end-of-file. Most often, these errors can be corrected by use of a more 
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(> complete search path or a quick examination of the files and options used 
28 to invoke the compiler. 


Errors 


An (E) Error message indicates that the compiler has encountered a syntax 
| or logical error. By default, the compiler adopts the view that it is not 
| prudent to generate code after errors of severity (E): 


Example 


1 int a[10; 
>> (E) syntax error; unexpected symbol: ‘;* 
2 main() 
3 { 
4 ++; 
| : >> (E) operand is not an lvalue 
5 } 
2 Errors 


(> Warnings 


A (W) Warming message indicates code that, even if not erroneous, can 
result in unexpected behavior of the program: 


Example 
1 int *p=1024; 


A 


>> (W) address expected in initialization of ‘p' 


3. foot) 
4 { 
5 p="char-string"; 


A 


>> (W) operands of ‘=" have incompatible types 
6 } 
2 Warnings 
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Informational Messages 


Example 


Finally, an (I) Informational message is similar in nature to a (W) Warning, 
but is less likely to alter user program behavior. By default, (I) 
Informational messages are suppressed but can be displayed by using the 
-nQ (no Quiet) option, as in: 


mecxx -nQ file.c 


For examples of (I) Informational messages, see listings throughout this 
section. 


Error Severity and Code Generation 


There is a limit to the number of (E) messages that can be produced in every 
compilation. This limit is 20 by default and can be changed with the option 
-Q with a numeric argument. 


Note that ANY (E) Error will cancel code generation but that companion 
will be continued for diagnostic purposes. ; 


Changing Error Count Limits 


Example 


14 


If you desirea listing showing more or less than the default of 20 (E) errors, 
you can change the default by using option -Q with a‘numeric value. 
For instance, -Q0 will stop the compilation if any (E) errors are detected: 


1 array[100]; 
(I) [ANSI] missing type; *int’ assumed 
2 aint *if; 


{E) syntax error; unexpected symbol: "if" 


>> (F) too ‘many errors 


2 Errors 1 Informational 


Note that level (W) and level (I) occurrences do not participate in the count. 
The default limit of 20 may seem low, but the compiler does a good job at 
avoiding cascading of errors: 
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Example 


undefined [*undefined] (undefined) ; 
>> {E) undeclared identifier ‘undefined" 
4 } 
1 Error 


Suppressing Error Messages 


With the option -Q, it is also possible to suppress error messages of a certain 
severity level and below. The default setting is given by -Qi, which means 
suppress (I) Informational messages. Fatal errors cannot be suppressed. The 
final summary can also be suppressed with the -Qs (the "Quiet summary" 

option). 


To selectively suppress diagnostics of varying severities, see the following 
table: 


(1) 
(1),(W) 
(1),(W),(E) 


summary 
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Example 
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To see how the -Q option can be used, compare the following: f 4 


mcocoxx -nQs -Qw -05 -1 input.c 


1 array[100]; 
2 int *p=7; 
3 int vet[1i0; 


A 


>> (E} syntax error; unexpected symbol: '; 
1 Error 1 Warning (suppressed) 1 Informational (suppressed) 


In the above example, option -nQs (default) causes the summary to not be 
suppressed, option -Qw suppresses (D Informational and (W) Warning 
messages, and option -Q5 limits the compile-time errors allowed to five. 
Also, option -I causes a listing on the standard output. 


mecxx -Qs -Qw -Q0 -1 input.c w 


1 array(100]; 
2 int *p=7; 
3 int vet{10; 


AA 


>> {E) syntax error; unexpected symbol: *;" 


>> (F) too many errors 


In this second example, option -Qs suppresses display of the summary, 
option -Qw suppresses (I) Informational and (W) Warning messages, and 
option -Q0 sets the error tolerance to zero, that is, the occurrence of any 
error will terminate compilation. 
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(~The Compilation Driver and its Uses 


The compiler features a powerful compile/assemble/link driver. In 
addition to simplifying the compiler invocation and builds of your 
applications, features of the driver can be used to customize the compilation 
environment for your development needs. 


Compilation Driver Option Evaluation 


Compile-time options are parsed left to right. Hence an option can be 
superseded simply by specifying its new setting further along in the 
invocation string. Note that the input file names do not need to occupy any 
specific position in the invocation line and that the last options encountered 
in the invocation string will apply for all files being compiled: 


Example 


mecxx -g -1l -Flp44 main.c read.s ser.lib -ng -F1lp100 -g -ng 


This invocation will compile main.c without debug (rightmost -ng) and 
| with a listing page length of 100 lines. 
! a The left to right parsing feature is most convenient whenever certain option 
settings need to be changed frequently. As an application, consider the 
following UNIX csh script: 


compile:set extraoptions="Sargv[2-S$#argv]’ 


mecxxX $1 -c -g -O -Flp44 $extraoptions 


The first line assigns to extraoptions all the invocation arguments which 
follow the first argument (the file name): 


Example 


% compile test.c — will compile test.c with "normal" option 


% compile test.c -g -1 -~- will compile test.c with extra options -g -l 


% compile test.c trick.c - will compile test.c and trick.c 
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Pragmas and Options . ) UL) 


Example 
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The compiler provides a powerful #pragma facility which can be used 
effectively in a large variety of cases: the #pragma option. By using the 
ANSI construct #pragma option, command line options normally set 
through the driver may be set within the program file itself. This directive 
allows you to specify local compile options inside the source file itself by 
simply listing them in their UNIX syntax. These options will override those 
on the invocation line, since they are the “rightmost” (by definition they 
follow the command line) and will affect the compilation of the entire file, 
not just code subsequent to their occurrence. 


A typical use of #pragma option is with makefiles which compile a related 
group of sources. One of the files in this group may require particular 
options, like optimize for space, or no debug. Normally, the makefile would 
apply the same set of options to all the files. By using a #pragma option, 
that file would additionally set its own options, as in: 


#pragma option -ng 


Example 
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“#pragma option -ng 
funct2()/* don't include debug info */ 


You must observe two caveats. First, the only options that can be specified 
are true compiler options, like -g, not options which control driver ©) 
behavior, like the options -S, -e, or -l. Because the driver decides how to 

proceed before reading any input files, driver-specific options within the 

file will have no effect. Furthermore, many input files could have this 

pragma, and the driver would not be able to obey them all. Secondly, the 
driver-specific options apply to the whole compilation, regardless of the 

pragma position in the source. In other words, the options cannot be 

toggled on and off to affect only portions of a source module. For example: 


#pragma option -g 
functl{}/* always includetdebug info */ 


The compiler will not use different optimization criteria for functions 
funct10 and funct2(). Since -ng was encountered last, it will apply to the 


whole module. @ 
: | 
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es The convenience of this directive is shown in the following two modules: 


“ee module a: 


#pragma option -NTcode_a -NIdata_a -NCdata_a -NSdata_a 


#pragma option -NLdata_a 


module b: 


Example 
#pragma option -NTcode_b -NIdata_b -NCdata_b -NSdata_b 


#pragma option -NLdata_b 


The -N group can be used to assign names to the compiler-generated 

sections. At link time, it will be possible to locate separately the sections in 

module a and module b. Thus, you need not compile with command line 
(~ options because they are specified in the module itself. 


The View Options 


The driver comes with powerful “inspection” options for viewing 
information that deals with, for example, the effect of invocation options on 
compilation, the total time spent compiling, or compiler version and 
revision levels. 


View Invocation Settings 


The option -Vi (as in View invocation) shows the driver working step by 
step. Invoking the compiler as: 


Example 


mecxxX ~Vi -emy_linkfile main.c read.s break.o scr.lib 
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yields: ‘ ) 


Example 


main.c: 


fusr/mri/bin/cfexxX -Ri/tmp/main.1 main.c 


/usr/mri/bin/cbhexx /tmp/main.1 > /tmp/main.s 
/usr/mri/bin/asmxx -o main.o /tmp/main.s 

rm -f£ /tmp/main.s 

read.s: 

/usr/mri/bin/asmxx -o read.o read.s 

Linking: 

/usr/mri/bin/1nkxxX -o main.x 


-c my_linkfile main.o read.o break.o 
scr.lib 


View Dump 


The option -Vd {as in View dump, or View debug) works exactly like -Vi : 
but does not actually execute the various compilation steps. The output of o) 
-Vd can be redirected toa file, with the net result of creating a script for 

future compilations. 


Example 


mecxx *.c *.5 *.0 *.1lib /usr9/new/scr.lib -Vd > compile.cmd 
chmod +x compile.cmd 


Since the driver itself is not a script, but rather a fast C program, there is 
little or no convenience in using: 


Example 


mcexx <other options> -vad > script_file 


Occasionally, however, for debugging purposes, redirecting the output of 
compiles with option -Vd can be useful. 
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= View Time sie a. 


The option -Vt (as in View time) causes compile-time information to be 
output. This option is not supported on the MS-DOS host. 


Example 


/usr/mri/bin/cfexx -Ri/tmp/x.1 -g x.c 
time: 0.699 sec 

fusr/mri/bin/cbexx /tmp/x.1 > x.s 
time: 0.416 sec 


As shown in the example, the option -Vt implies -Vi as well. Note that 
ctexx and cbexx are the compiler’s front-end and back-end respectively. 


View Which Version 


Finally, the option -Vw (as in ‘View who am I”) gives a list of the versions 
of the tools the driver utilizes. 


Invoking: 2 ‘ 


| Example 
“mecxx -Vw ~S~ 


reveals the version header: 


Microtec Research MCCXX ANSI C Compiler Version yy 


Copyright {c) 1991 Microtec Research, Inc 
ALL RIGHTS RESERVED. 
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Customizing Compilation Driver Defaults VY 


If you are not satisfied with the default setting of some of the options, you 
may want to use the driver option -d<filename>. This option allows you to 
customize your compiles or allows the system administrator to establish 
installation defaults. 


The driver will read the line(s) in the file specified after -d as though it were 
specified in the command line. More than one line can be provided; the 
new-line character will not be part of the options: 


Example 
/usr/misc/project_alpha_defaults contains 
-g 
-Flp66 
-e/usr/misc/project_alpha_linkfile 
-DDEBUG_MODE -DHOST=SUN4 


Using the proper alias will ensure that your customization is in force: 


Example 


alias meccxx “mccxx -d/usr/misc/project_alpha_defaults" 
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_(~ — Reporting Problems 


Microtec Research tests its compilers very extensively. However, even with 
the most exhaustively tested software, you may still encounter a new bug. 
In the event that you come across a problem in Microtec Research tools, first 
check the Release Notes for information on the problem, and if not there, 
please report it promptly to Microtec Research Technical Support. 


Preparing a Test Case 


Example 


The best way to report a bug is to provide a small test case to recreate the 
problem. Unfortunately, the complicated net of include files and intricate 
macros which comprise a real program can make it difficult to isolate a bug 
and produce a clean test case. From our point of view, the ideal test case is 
a preprocessed “flat source” file. 


To obtain a flat source, we recommend using the driver option -P to invoke 
the preprocessor in stand-alone mode and to produce an .i flat file, in which 
all includes and macros have been merged and expanded: 


mecxx -P <your_file>.c 


Edit this file and add a #pragma option line at the top, specifying the 
compile options you used on the actual code exhibiting the problem 
behavior. To be sure that the bug did not disappear in the process of 
“flattening” (after all, it could be a preprocessor bug), try to reproduce the 
problem with the final .i file, invoking the driver without compiler options 
(the in-line #pragma option will set the options for you): 


mecxx <your_file>.i 


Reporting Bugs to Microtec Research 


To summarize, if you think that you have encountered a bug in the 
compiler: 


¢ Build a test case source file which exhibits the problem when compiled 
e Compile the test case with option -P 
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© Edit <your_file>.i by adding a #pragma option line at the top, with the : ) 
list of the compilation options from your original command line. Any 
comments on the problem should also appear in the source. For an ex- 
ample, see Reporting Bugs Example in the appendix which pertains to 
your compiler. An example is shown below. 


e Verify that the problem is still there. 


e Call our toll-free number (800) 950-5554, ask for Technical Support, and 
make arrangements to supply Microtec with the test case. 


¢ Thefiles <your_file>.s and <your_file>.l may also be useful. They can best 
be obtained by compiling with the options -1, -S, and -Fsm. 


Example 


<your_file>i: 
#pragma options -Md -Os 
/* access to an array larger than 512k is wrong */ 
. test case... 
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(~ Miscellaneous Tips 


Compiling Large Programs. 


The Microtec Research ANSI C Compiler reuses memory effectively. As 
such, compiling even large programs should not give rise to any space 
problem even on systems like PC/MS-DOS where available memory is 
limited. 

If, in compiling your application, your programs cannot be compiled due to 
lack of memory, this section will help you to alleviate the problem. 


The compiler can run out of memory either because the source file contains 
too many symbols or because a single function/procedure in the module 
contains a very large number of program statements. In most cases, you just 
will have to break down the large function / procedure into smaller routines. 
This can result in superior code generation as well, since smaller procedures 
are conducive to generating more highly optimized code.. 


Before you start restructuring your code, however, there are several . 
alternatives you may want to try: 


e Preprocess the source separately. Macro symbols may be competing 
with program symbols. Try recompiling the .i file, output by the pre- 
processor: anes ° =< 


mceexx -P biggo.c 


mcecxx biggo.i 


Example 


e¢ Compile with -nA (pre-ANSI). The ANSI branches of standard header 
’ files are full of prototypes which, in turn, are full of parameters, in: par- 
ticular <stdio.h>. Each one of them requires a symbol or descriptor 
which uses available memory. By specifying -nA, the pre-ANSI head- 
ers, without prototype information, will be selected instead. 


To see the difference, compare: 


extern int vfprintf(FILE *stream, const char *fmt, va_list arg); 


extern int vfprintf{); 


Try eliminating the use of <stdio.h> or restructuring your .h files. 
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e Check for macros like pute, gete, and putchar. They expand into a large l ) 
number of program elements or tokens; putchar normally generates 
about 30 of these tokens each time it is used. Changing a call to putchar 
into a call to a routine which, in turn, calls putchar may drastically re- 
duce the size of your function as well as the size of your code. 


¢ Break large functions into smaller ones. 


® Compile large modules without optimization. 


Locating Header Files 


Sometimes you will need to know the exact origin of the header files 
included during a compile. The quickest access to this information is to use 
option -E, invoking the preprocessor and producing an “annotated” listing 
to standard output. 


If, for example, your file input.c contains: 


Example 


#include ‘*x.h* 
#include <stdio.h> 


then try invoking the compiler as: 


mecxx -~E input.c | more 


to obtain: 


Example 
#line 1 *input.c* 
#line 1 "./x.h* 


extern foo(struct tag *p); 


#line 2 ‘input.c*" 


#line 1 */usr/mri/include/mccxx/stdio.h* 


extern struct icbuf { 
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C~ By viewing the full path names of the include files used, you will eliminate 
7 any uncertainty about the actual headers used with your program. 


If you want to override the default path for the standard (<>) include file 
directory, use compile option -J. 


Viewing Current and Available Options: 


The options you may specify for a given compilation constitute a subset of 
ali the options which are in force during a compilation. Beyond the options 
which you choose to actively control, there are others with interesting 
default behaviors with features which could be useful. 


An easy way to learn about these “hidden options” is to compile an empty 
file, producing a listing to the default standard output. Whenever you 
receive a new version of the compiler, you may want to use this method to 
investigate what new features have been included in the release. 


Example 
mcecxxX -1 -y nil.c 


The “-y" option limits the compiler to checking the syntax of the program so 
Ss. that errors produced by an empty file are kept to a minimum. 


Customizing Listing Files 


The listing files produced by the Microtec Research ANSI C Compiler are 
intended for line printer output, with a default page length of 55 lines. You 
can change this number with the option -Flp<number>. The option -Flp0 is 
a special case which tells the compiler to prepare the listing for a continuous 
printout with no page breaks. 
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Toggling Program pun te) 
The pragmas: 


Example 


#pragma list on 
#pragma list off 


can be used to toggle the list option on or off. After either forcing or 
suppressing the listing of a section of program code, you very often wish to 
return to the default listing option, specified on the command line. 


Some compilers cannot restore the default settings of options once modified 
in-line. The compiler, however, provides a third #pragma as follows: 


Example 


#pragma list resume 


which restores whatever list option was previously in force. 


foo() 
} 
#pragma list off 
int invisible, visible; 
invisible=1; 
#pragma list on 
visible=99; 
#pragma list resume 
invisible=1; 


wo Donn nM & WN 


ied 
re oS 


#pragma list resume 
visible=99; 


roe 
wn 


} 
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( \ The listing produced will be: 


Example 


foot} 
{ 

#pragma list off 
visible=99; 
#pragma list resume 
visible=99; 


Notice that the listing option -1 must be set on the command line. 


Producing Assembly Language Listings 


You may want to analyze the assembly code produced by the compiler. To 
do so, specify the option -Fsm, which will merge the original C source into 
the assembly listing file in the form of appropriately placed comments: 


Example 


mccexx -S -Fsm heilo.c 
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Specifying Compile Search Paths O 


Itis very common to keep sources and objects in the same directory. 
However, it is also common to want different object versions of those 
sources. This is best accomplished by leaving the sources in their 
development directory(s) and compiling in a different directory to produce 
special object versions. The following is an example of leaving the sources 
in their development directory and compiling in a different directory to 
produce special object versions. Note the use of full path names on the 
source files. - 


Example 


cad ~john/no_debug_dir 
mccxx -ng ~john/new/*.c 
ed ~john/debug_dir 

mccxx -Gf -g ~john/new/*.c 


In the example, options -g and -ng specify debug or no debug. Also, note 
the use of the -Gf option. Using the -Gf option passes full path names into 
the debug file, making it possible for the XRAY Debugger to locate the 


source file. o 
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C~ Effective Use of In-Line Assembly — asm() 


To facilitate implementation of embedded systems, the Microtec Research 
compiler provides a powerful in-line assembly feature. The 
pseudo-function asm() allows you to insert one or more assembly language 
instructions into C source code to program processor-specific functions 
beyond the scope of C. 


In many ways, asm() resembles an actual C function: 
¢ asm() has the same syntax as a function j 
e asm()} normally takes one or more double-quoted string parameters as 


arguments 
e Some optimizations across asm() are prohibited as with other functions 


e asm() can return a value of any type, just like a function 


When code is generated, however, instead of pushing the parameter onto 
the stack and then calling the function, asm() “drops” its string parameters 
in the assembly language output file. After the last line of the string 
argument, it inserts code for returning a value just as a real function would. 


This last point gives asm() many possibilities. The return type of asm() is not 
eo pre-determined, but the default is int. For a detailed description and 

examples of the asm() statement, please refer to your Compiler Reference 
Manual. 


For the purposes of the following example, we can assume that asm() 
returns an int. Since int values are returned in dO, the content of this register 
will be made available to code invoking the pseudo-function. 


Observe the following fragments showing a normal function call: 


Example 


int f(int x); 
Static int result; 
foo{) 

{ 

result=f(1); 

} 


generates: 
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Example 


Example 
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resultcsf(1); 
pea 1 
jsr _f 


addq.1 #4,sp 
move.l1 d0,_.SO_result 


At the end of the function, the contents of g0 are moved into result, as the 
return value of the function £(). Implementing the function with asmQ), 
instead of an actual function call, results in the following: 


result=asm(* move.1 d3,d0°); 


which generates: 


result=asm(*" move.1] d3,da0"); 
move.1 d3,d0 


move.1 d0,_.SO0_result 


The example illustrates that the arguments of asm() are responsible for 
making the returned value available in g0. The result of this example is to 
get the current contents of 80960 register g3 into program variable result. 


asm) also has an optional first parameter which is a standard C type 
dediaration. This allows you to spedfy the return type for the 
pseudo-function call. Thus, asm() can return any type, including a full 
struct! 


Note that since the asm() pseudo-function is not a true function, it is not 
subject to prototyping or assignment restrictions, and assignments can be 
made from it without need for recasting. 


As an exercise, try to determine what the following do: 
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AY Examples 
Example 1: int *spsasm(* move.l sp,d0‘); 
Example 2: int d0=asm(); 
Example 3: struct tag {int info; struct tag *next;); 
asm(struct tag," *} .next->info=0; 
Example 4: if ( asm(unsigned char,* tst.1 dO") } 


exec( }; 


Example 5: char *sp_before, *sp_after; 


sp_before=asm(char *,* move.1] sp,d0"); 
Denmark {); 

sp_after =asm(char *,* move.l sp,d0*); 
if (sp_before != sp_after) 


printf(*There is something rotten in Denmark‘); 


| C> Using #define for Readability 


You can make asm statements more readable with the #define directive. 
Example: 


#define D4 asm(int, * move.1] D4,D0°); 
#define DS asm(int, * move.1 DS5,p0°); 


if (D4>D5) 


) This example shows that it is possible to access every single machine device at the 
| C level. The overhead is confined to a move. For Do (and FPo), not even this move 
is required. 
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Variable Names Inside asm() 


You can specify global and local variables by name inside an asm string. A global 
variable x can easily be represented at assembly level by _x. Local variables, on the 
other hand, are represented by frame offsets or by registers that can change from 
one release of the compiler to the next. Their addresses can even change between 
two compiles if new code or variables have been added to a procedure. Hence, there 
is no easy way to represent local variables. 


Note 


This feature in not supported in the MCC88K Compiler. 


Back Quoting Variable Names 


The Microtec Research C compiler lets you insert variable names in any asm string 
by simply quoting them with a back quote (~). Since it is unlikely that this character 
will appear in any assembler statement, Microtec Research has chosen it as the 
default. 


Example: 


foot) 
{ 
int automobile, garage; 


asm(* move.l] ‘automobile’, ‘garage‘*); 


The actual addresses of the inserted variables will be supplied while conforming to 
the usual scope rules. According to the memory/register binding in force for the 
compilation, the above example will gencrate: 


move.1 12(a6),d4 


if you want to use a character other than the back quote, use the -uichar option to 
change the insert character to char. 


It is recommended that you use the -uichar option inside a #pragma option instead 
of on the invocation line because you may not want to change the insert character 
from compile to compile. 
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Inserts and Global Variables 


Inserts are still recommended for global variables. Variable names inside a string 
are not affected by compiler options like /prepend=dot (VMS) or -upd (UNIX/ 
DOS). However, inserts are option-sensitive. 


Example: 


#pragma option -upd 
/* prepend a dot to all global names */ 


asm(* move.] _global,_global2"); 


In the example above, the -upd option cannot affect the global names inside the 
string. 


asm(* move.] ‘global’, ‘global2’"); 


In this example, the inserts will reflect the -upd option. 
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asm() Versus #pragma asm / #pragma endasm ' at ) 


Since asm is a pseudo-function, it can only be used where a normal function can be 
invoked, namely inside a procedure. Outside a procedure, any number of unquoted 
assembler instructions can be inserted between the pair #pragma asm and 
#pragma endasm. 


Example: 
#pragma asm 
#if _FPU 
fmove.1 ROUNDING, FPCR ; set rounding mode 
#fendif 
#if _CHAR_SIGNED 
#if (_68020 |i _68030 || _68040 || _cCPU32) 
extb.1 D1 
move.1 D1,DO 
#felse 
ext .w D1 ; Sign extend f 
ext.1 D1 
move.1 Di, DO 
#fdefine XXX unsigned.s 
#endif 
felse 
move .q #0, D0 ; zero extend 
move .b D1, DO 


#define XXX unsigned.s ‘ 
#endif 


#include XXX 
#pragma endasm 


Note the use of user-defined macros such as xxx and predefined ones such as _FPU 
and _CHAR_SIGNED. The full preprocessor functionality is available inside a 
#pragma asm/#pragma endasm pair. However, inserts cannot be used. 
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Determining the Size of a Type 


Example 


The compiler diagnostics contain a shortcut to finding the size of any Cc 
type. Knowing the size of a type is useful for double checking type defaults 
and for establishing the size of complex structures and unions. 


To use the compiler diagnostics to derive type-size information, try passing 
a type (instead of a variable or constant) as an argument toa procedure. The 
resulting diagnostic will be a (W) Warning informing that the type has been 
replaced by its size. For example, 


{ 

packed struct tag 
{ 
char a; 
short b; 
char ¢; 
}3 


1 
2 
3 
4 
5 
6 
7 
8 
9 
0 


f(struct tag); 
Aw 

type used as argument; replaced with its sizeof: 
glint); 

type used as argument; replaced with its sizeof: 
h(const char *(20]); 

type used as argument; replaced with its sizeof: 
} 
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ANSI Keywords const and volatile 


Two of the more useful ANSI extensions are the keywords const and 
volatile. Both keywords can be used for purposes beyond the most 
obvious ones. 


Using const for Data Protection 


Example 
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To review, a variable with the type modifier const cannot be modified for 
the scope of its declaration, and, if the variable is static or global, will likely 
be placed in ROM. 


The ANSI keyword const can also serve another function: data protection. 
Suppose that in your program there is a data structure initialized and 
modified by one module, the “implementor module’, that must be 
accessible as read-only to some other “consumer” modules, and, for the 
purposes of this discussion, a procedural interface is considered inefficient. 
You can declare the data structure as const in the consumer modules while 
retaining the ability to modify it (mon-const) in the implementor module. 
As long as the definition of the data structure is in the implementor module 
(non-const declaration), the data will not end up in the const section yet the 
consumer modules will not be permitted to modify the data. 


module a - the implementor: 


int sacred_data = 0;/* sacred_data Gefined here */ 


void implementor(int x) 


{ 


sacred_data=x+2;/* we can alter sacred_data */ 


} 


module b - the consumer: 


extern const int sacred_data; /* defined elsewhere */ 
char consumer () 


{ 
display ({sacred_data); /* sacred_data is read-only */ 
} 


vy 


ne ee wer ae SS balsas 
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Optimization and volatile 


The keyword volatile indicates to the compiler that the data structure in 
question is subject to modification which is asynchronous to linear program 
flow. 


In practical terms, volatile tells the compiler to refrain from optimizing 
accesses to a given variable, since external events can alter the variable’s 
contents at an undetermined moment. Typically, this would apply to 
memory-mapped I/O devices, areas of memory which are the target of 
DMA accesses, or to shared data structures in a multitasking environment. 
In the presence of the volatile keyword, the compiler prevents optimization 
of accesses to the variable. As a by-product, volatiles NEVER end up as 
register variables. Hence, the volatile attribute can also be treated as the 
“noregister” keyword. 
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Recommended Options O 


The following are recommendations for option usage to achieve optimal 
results in the areas of compile speed, code generation, compactness, ANSI 
compliance, and module size. These factors are not necessarily mutually 
exclusive but do influence one another. 

Fastest Compilation 


Use options -ng -nOg (no debug, no global optimization) 


Fastest Generated Code 
These options are listed under Fastest Generated Code in the appendix which 
pertains your compiler. 
ANSI-compliant Code 
Use options -nx -A (no Microtec extensions, ANSI 
extensions) 
Accept Broadest C Language Definition 
Use options -x -A (Microtec and ANSI extensions) 


aa 


Oo 


(> Appendix A: MCC68K Considerations and 
Examples 


Microtec Research Extensions 


Just as -A selectively activates ANSI features, the -x option activates 
extensions to the C language that Microtec Research has implemented to 
ease embedded and systems programming. The following is a list of the 
extensions provided by Microtec Research. 


the asm() pseudo-function, for use of in-line assembly code including 
variable names inside asm() 


interrupt procedures 

the packed keyword to avoid padding in structures 

the packed keyword to reduce the size of small enumerations 
the char / short / long underlying type for bit-fields 
in-lining of several library functions 


Fastest Generated Code 


Use options -O (global optimization, instruction scheduling, 


and inlining) 
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Accessing Fixed Layout Records O 


In certain applications, operating systems or data transmission, for 
example, you may encounter data structures which have a fixed or 
predefined layout. If that layout is not easily accessible, the compiler 
provides a number of extensions to make it possible to process those 
structures. 


Consider the following hypothetical data structure: 


Example 


31 26 25 24 23 16 15 8 7 0 
Festa. die siete chenta cient aie diene ete cies che aint siete ee aetna sient chee shee atte teeta ile ciate cietin Sie ele adie ete ee cee es ee 2 
{ mask Icypel channel_no Icfolxizivistlliri 


a ee en ee i ee ee ee er ee ee ee ee ee er ne ie ee 


Such a structure would be impossible to describe in terms of Standard C. 
Note, for instance, how channel_no, a short, starts on an odd address. 


Microtec Research compiler, however, allows the description of the above 
structure using a combination of packed struct, packed enum, and ( ) 
“economy” bits. 


Example 


#packed options -p68020 
packed struct 
{ 
packed struct 
{ 
signed char mask : 6; 


signea@ char type : 2; 
} interrupts; 
short int channel_no; 


packed enum {c=128, o=64, x=32, 2=16, 
v=8, s=4, 1=2, xr=1U } flag; 
} psw = { { Oxlf,0}, 1, v | x | $s}; 


assert (sizeof (psw)==4); 


Appendix B: MCC88K Considerations and 
Examples 


Microtec Research Extensions 


Just as -A selectively activates ANSI features, the -x option activates 
extensions to the C language that Microtec Research has implemented to 
ease embedded and systems programming. The following is a list of the 
extensions provided by Microtec Research. 


e the asm( pseudo-function, for use of in-line assembly code 
e the char / short / long underlying type for bit-fields 
¢ in-lining of several library functions 


Fastest Generated Code 


Use options -Og -Or (global optimization, instruction scheduling) 


O 


_ (> Appendix C: MCC960 Considerations and 
Examples 


Microtec Research Extensions 


Just as -A selectively activates ANSI features, the -x option activates 
extensions to the C language that Microtec Research has implemented to 
ease embedded and systems programming. The following is a list of the 
extensions provided by Microtec Research. 


e the asm() pseudo-function, for use of in-line assembly code including 
variable names inside asm() 


¢ interrupt procedures 

e the packed keyword to avoid padding in structures 

e the packed keyword to reduce the size of small enumerations 
e the char / short / long underlying type for bit-fields 

e in-lining of several library functions 


oO Fastest Generated Code 


ry Use option -O (global optimization) 


C 


C-1 
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Accessing Fixed Layout Records 


In certain applications, operating systems or data transmission, for 
example, you may encounter data structures which have a fixed or 
predefined layout. If that layout is not easily accessible, the compiler 
provides a number of extensions to make it possible to process those 
structures. 


Consider the following hypothetical data structure: 
Example 


31 26 25 24 23 16 15 87 0 
S lnals cel Seni sinless eats sienla siete slaatin iat ils steel alee nls eels alias inate Seeks ete eel eae ads els et ele Shel et ils ade te le 
| mask }type| channel_no IclolIx{zlvlsllirt 


Se a OO CO ee ee ee eres 


Such a structure would be impossible to describe in terms of Standard C. 
Note, for instance, how channel_no, a short, starts on an odd address. 


Microtec Research MCC960, however, allows the description of the above 
structure using a combination of packed struct, packed enum, and 
“economy” bits. 


Example 
packed struct 
{ 
packed enum {c=128, o=64, x=32, z=16, 
v=8, s=4, 1=2, xr=1U } flag; 
short int channel_no; 
packed struct 
{ 


signed char type : 2; 


signed char mask : 6; 
} interrupts; 
}psw={vixis, 1, { 0, OxlF } }; 


assert (sizeof (psw) ==4); 
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Notes 


Microtec Research, incorporated 

Microtec Research, Incorporated, Santa Clara, California, has been creating solutions for 
microprocessor developers since 1974. Founded by specialists in microprocessor 
technology, Microtec Research has provided over a decade of experience in the design, 
development, and support of software products for microprocessors. 

Microtec Research’s languages and software development tools have been designed for the 
professional developer of microprocessor applications. Microtec Research’s thousands of 
customers throughout the world represent virtually every business, scientific, 
governmental, and educational activity requiring microprocessor program generation 

and testing. 
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